home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UMenuMgr.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  12.4 KB  |  320 lines  |  [TEXT/MPS ]
  1. // UMenuMgr.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UMENUMGR__
  5. #define __UMENUMGR__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __MACAPPTYPES__
  10. #include "MacAppTypes.h"
  11. #endif
  12.  
  13. #ifndef __ULISTITERATOR__
  14. #include "UListIterator.h"
  15. #endif
  16.  
  17. #ifndef __UOBJECT__
  18. #include "UObject.h"
  19. #endif
  20.  
  21. // Toolbox
  22.  
  23. #ifndef __MENUS__
  24. #include <Menus.h>
  25. #endif
  26.  
  27.  
  28. //----------------------------------------------------------------------------------------
  29. // Constants
  30. //----------------------------------------------------------------------------------------
  31.  
  32. const ResNumber mFirstMenu = 1;                    // MacApp manages menu titles
  33.                                                 // mFirstMenu..mLastMenu generically 
  34.  
  35. const ResNumber mApple = mFirstMenu;            // MacApp does not disable any commands in
  36.                                                 // this menu 
  37.  
  38. const ResNumber mFile = mApple + 1;                // Default ID of the File menu 
  39.  
  40. const ResNumber mEdit = mFile + 1;                // Default ID of the Edit menu 
  41.  
  42. const ResNumber mDocument = 20;                    // Document Menu
  43.  
  44. const ResNumber mOpenDocEdit = 21;                // Edit Menu with OpenDoc items
  45.  
  46. const ResNumber mEditionMgrEdit = 30;            // Edit Menu with Edition Mgr support
  47.  
  48. const ResNumber mMail = 31;                        // Default ID of the Mail menu 
  49.  
  50. const ResNumber mDebug = 900;                    // read in if debugging is turned on;
  51.                                                 // number corresponds with debugging
  52.                                                 // command numbers 
  53.  
  54. const ResNumber mDebugFlags = 127;                // read in if debugging is turned on;
  55.                                                 // number corresponds with debugging
  56.                                                 // command numbers 
  57.  
  58. const ResNumber mDebugFont = mDebugFlags - 1;    // read in if debugging is turned on;
  59.                                                 // number corresponds with debugging
  60.                                                 // command numbers 
  61.  
  62. const ResNumber mDebugSize = mDebugFont - 1;    // read in if debugging is turned on;
  63.                                                 // number corresponds with debugging
  64.                                                 // command numbers 
  65.  
  66. const ResNumber mLastMenu = 63;                    // MacApp disables menu titles
  67.                                                 // mFile..mLastMenu generically 
  68.  
  69. class TMenuBarManager : public TObject
  70. {
  71.     MA_DECLARE_CLASS;
  72.     
  73. public:
  74.     ResNumber    fDisplayedMenus;
  75.     ResNumber    fPreferredMenuBarID;
  76.  
  77.     ResNumber    fDisplayedHierMenus;
  78.     ResNumber    fPreferredHierMenuBarID;
  79. #if qContainer
  80.     Handle fAppMenuBar;
  81. #endif    
  82.     inline TMenuBarManager()
  83.     { }
  84.         // Empty constructor
  85.  
  86.     virtual ~TMenuBarManager();
  87.         // Destructor
  88.         
  89.     void IMenuBarManager( ResNumber otherMenus );
  90.         // Initialize the object
  91.  
  92.     virtual void Reset ();
  93.         // Called to indicate that there is no preferred menu bar
  94.  
  95.     virtual void SetPreferredMenuBarID (ResNumber theID);
  96.         // Called to indicate a preference for a menu bar
  97.  
  98.     virtual void SetPreferredHierMenuBarID ( ResNumber theID );
  99.         // Called to indicate a preference for a hierarchical menu bar
  100.  
  101.     virtual ResNumber GetPreferredMenuBarID ();
  102.         // Returns the ID of the preferred menu bar
  103.  
  104.     virtual ResNumber GetPreferredHierMenuBarID ();
  105.         // Returns the ID of the preferred hierarchical menu bar
  106.  
  107.     virtual void InstallPreferredMenus ();
  108.         // Called to actually install the preferred menus in the menu bar.
  109.  
  110.     virtual void AddHelpMenuItem( CStr255 helpText, CommandNumber helpCommand );
  111.         // Adds a help item to System 7's help menu (if available).  If 'helpText'
  112.         // contains the string '^0', the application name is substituted.
  113.         // helpText should almost always be "^0 Help" or "^0 Shortcuts"
  114.  
  115.     virtual void AddMenuItem(const CStr255& theMenuItemText,
  116.                              MenuID menuNumber,
  117.                              short insertAfterItem,
  118.                              CommandNumber theMenuItemCommandNumber);
  119.         // Adds a menu item to the specified menu
  120.  
  121.     virtual void DeleteMenuItem(CommandNumber theMenuItemCommandNumber);
  122.         // Deletes the menu item that is specified by the command number
  123. };
  124.  
  125. //----------------------------------------------------------------------------------------
  126. // CMenuIterator: A simple iterator for menu lists.
  127. //----------------------------------------------------------------------------------------
  128.  
  129. class CMenuIterator : public CHandleIterator
  130. {
  131.     
  132. public:
  133.     CMenuIterator();
  134.  
  135.     virtual ~CMenuIterator();
  136.     
  137.     inline MenuRef CurrentMenu()
  138.     { return (MenuRef)CurrentHandle(); }
  139.         // returns the current window
  140.  
  141.     inline MenuRef FirstMenu()
  142.     { return (MenuRef)FirstHandle(); }
  143.         // Resets the iterator to begin again and returns the first window in the window list
  144.  
  145.     inline MenuRef NextMenu()
  146.     { return (MenuRef)NextHandle(); }
  147.         // increments and then returns the window in the window list
  148.  
  149. protected:
  150.     virtual void Advance();                    // override
  151.         // Advances the iteration
  152.  
  153. };
  154.  
  155. //----------------------------------------------------------------------------------------
  156. // typedefs for procedural parameter types.
  157. //----------------------------------------------------------------------------------------
  158.  
  159. typedef void (*MenuSetupType) (void* yourDataPtr);
  160.  
  161.  
  162. //----------------------------------------------------------------------------------------
  163. // Global variable declarations.
  164. //----------------------------------------------------------------------------------------
  165.  
  166. extern TMenuBarManager* gMenuBarManager;
  167.     // Used to manage the installation of preferred menu bars. 
  168.  
  169. #if qDebug
  170. extern Boolean gTraceSetupMenus;
  171. #endif
  172.  
  173.  
  174. //----------------------------------------------------------------------------------------
  175. // Global variable declarations: The following routines all recognize command numbers of
  176. // the form -(256 * menu + item) and -(256 * menu). The former is used when there is no
  177. // command number; the latter to enable/ disable a whole menu (rare) 
  178. //----------------------------------------------------------------------------------------
  179.  
  180. Boolean CommandEnabled(CommandNumber command);
  181.     // Returns true if the given command is currently enabled. 
  182.  
  183. CommandNumber CommandFromMenuItem(short menu, short item);
  184.     // Returns the command number for the given menu ID and item number. If the item
  185.     // number is positive, the command table is search for the given menu/ item pair. If
  186.     // found, the corresponding command number is returned. If not found, the number
  187.     // returned is equal to -(256 * menu + item). If the item number is negative, the
  188.     // number returned is equal to -item number.
  189.  
  190. void CommandToMenuItem(CommandNumber aCommand, short& menu, short& item);
  191.     // CommandToMenuItem returns the menu ID and item number of the given command. If
  192.     // aCommand is positive, the command table is searched for aCommand. If it is found,
  193.     // CommandToMenuItem returns the corresponding menu ID and item number. Otherwise menu
  194.     // and item are set to zero. If aCommand is negative, the menu number is the upper
  195.     // eight bits, and the item number the lower eight bits, of the absolute value of
  196.     // aCommand. (This implies that menu id's must be <= 127 and item numbers must be
  197.     // <= 255.)
  198.  
  199. MenuRef CommandToComponents(CommandNumber command, MenuID& menuNo, short& itemNo);
  200.     // CommandToComponents returns the menu ID and item number of the given command. as
  201.     // well as the MenuRef if the command exists.Otherwise it returns nil.
  202.  
  203. void CommandToName(CommandNumber aCommand, CStr255& menuText);
  204.     // Return the text of the menu item for the given command. 
  205.  
  206. void Enable(CommandNumber aCommand, Boolean canDo);
  207.     // Enable or disable a command 
  208.  
  209. void EnableCheck(CommandNumber aCommand, Boolean canDo, Boolean checkIt);
  210.     // Enable/ Disable and check/ uncheck a command 
  211.  
  212. MenuRef GetResMenu(ResNumber menuResID);
  213.     // Utility that just does GetResource('MENU', resourceID), so that it works for menus
  214.     // not currently in the menu bar. (You cannot call GetMenu more than once for the same
  215.     // menu, so you can use this (or MAGetMenu which is preferred) instead.)
  216.  
  217. void AddMenuBar(ResNumber itsID, Boolean isHierarchical);
  218.     // Add all the menus in the menu bar to the applications menus. Note that hierarchical
  219.     // must be treated differently from regular menus in that they are added with
  220.     // InsertMenu(, -1). We can't use GetNewMBar here because we want to call MAGetMenu
  221.     // for each menu in the MBAR, and GetNewMBar would not do that for us.
  222.  
  223. MenuRef GetIndMenu(ResNumber itsID, ResNumber itsIndex);
  224.     // Return a menu handle to the Nth menu in a menu bar.
  225.  
  226. short CountMenus(ResNumber itsID);
  227.     // Returns the number of menus in a menu bar.
  228.  
  229. MenuRef ConvertToMenu(Handle CMNUHandle);
  230.  
  231. void InitUMenuMgr();
  232.     // Initializes this unit, and must be called before using any other part of this unit.
  233.     // Loads the command table and sets up the NULL menu proc.
  234.  
  235. Boolean IsManagedMenu(MenuRef theMenu);
  236.     // given a MenuRef, this function returns true if it is a managed menu in our menu
  237.     // handle table 
  238.  
  239. Handle MAGetNewMBar(ResNumber menuRsrcID);
  240.     // Equivalent to the Menu Manager's GetNewMBar except it explicitly sets the menu
  241.     // bar's colors. 
  242.  
  243. void MAInsertInMenuTable( MenuRef theMenu, ResNumber menuResID );
  244.     // Inserts theMenu in the private gMenuTable. 
  245.  
  246. void MAInsertMenu(MenuRef theMenu, ResNumber menuResID, MenuID beforeID);
  247.     // Equivalent to the Menu Manager's InsertMenu with the addition that the MAInsertMenu
  248.     // looks for an 'mctb' resource whose id is the menu's id (as specified by menuResID),
  249.     // and if it is present applies the 'mctb' to the menu.
  250.  
  251. MenuRef MAGetMenuRef(MenuID menuID);
  252.     // Similar to GetMHandle, but also checks the global menu table list 
  253.  
  254. MenuRef MAGetMenu(ResNumber menuResID);
  255.     // Not quite equivalent to GetMenu because it doesn't load the menuDefProc or color
  256.     // table yet. It does, however, let you get the MenuRef without calling GetMenu
  257.     // more than once.It tries the menubar first and then calls GetResMenu if necessary.
  258.  
  259. void NeedCalcMenuSize(MenuRef aMenuRef);
  260.     // This procedure is called as part of the menu setup process and indicates that the
  261.     // given menu needs CalcMenuSize. You must explicitly call this if you use change a
  262.     // menu by means other than those supplied in this unit (e.g. you insert or delete
  263.     // items from a menu). Failure to do so will result in improperly sized menus.
  264.  
  265. void SetCommandIcon(CommandNumber aCommand, Byte menuIcon);
  266.     // You should call this (instead of the Toolbox's SetCommandIcon) for menus that are
  267.     // in the range [1..mLastMenu]. In addition to changing the menu this tells MacApp
  268.     // that the menu's size needs to be recomputed.
  269.  
  270. void SetCommandName(CommandNumber aCommand, const CStr255& menuText);
  271.     // You should call this (instead of the Toolbox's SetItem) for menus that are in the
  272.     // range [1..mLastMenu]. In addition to changing the menu this tells MacApp that the
  273.     // menu's size needs to be recomputed.
  274.  
  275. void SetIndividualCommandName(CommandNumber aCommand, ResNumber rsrcID, short strIndex);
  276.     // Does a GetIndString with the rsrcID & strIndex; and then a SetCommandName. 
  277.  
  278. void SetMenuState(CommandNumber aCommand,
  279.                   ResNumber rsrcID,
  280.                   short falseBuzzItem,
  281.                   short trueBuzzItem,
  282.                   Boolean stateVariable);
  283.     // IF stateVariable THEN
  284.     //        SetIndividualCommandName(aCommand, rsrcID, trueBuzzItem)
  285.     //    ELSE
  286.     //        SetIndividualCommandName(aCommand, rsrcID, falseBuzzItem);
  287.  
  288. void SetStyle(CommandNumber aCommand, /* Style */  short aStyle);
  289.     // You should call this (instead of the Toolbox's SetItemStyle) for menus that are in
  290.     // the range [1..mLastMenu]. In addition to changing the menu this tells MacApp that
  291.     // the menu's size needs to be recomputed.
  292.  
  293. void PerformMenuSetup(MenuSetupType TheMenuSetterUpper,
  294.                       void* yourDataPtr);
  295.     // Routine that perfoms the menu setup. 
  296.  
  297. void InvalidateMenus();
  298.     // Invalidate all the items on all the menus. Just like invalidation for windows it
  299.     // doesn't immediately change the visual appearance when you invalidate, it just means
  300.     // they are invalid and should be "setup" before showing them to the user again.
  301.  
  302. void ValidateMenus();
  303.     // Validate all the items on all the menus. Just like Validation for windows it
  304.     // doesn't immediately change the visual appearance when you Validate, it just means
  305.     // they don't need to be changed before showing them to the user again. 
  306.  
  307. Boolean MenusHavePendingUpdate();
  308.     // True if the menus are invalid and should be "setup" before showing them to the
  309.     // user. 
  310.  
  311. void InvalidateMenuBar();
  312.     // Invalidate the menu bar. It should be redrawn again. 
  313.  
  314. void MAHiliteMenu(short menuID);
  315.     // Just like the toolbox call HiliteMenu only avoids calling HiliteMenu if possible
  316.     // This saves an astonishing amount of CPU time.
  317. #endif
  318.  
  319.  
  320.